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TIM (The Interactive METATOY) is a ray-tracing program specifically tailored towards our research in METATOYs, which are 
optical components that appear to be able to create wave-optically forbidden light-ray fields. For this reason, TIM possesses 
features not found in other ray-tracing programs. TIM can either be used interactively or by modifying the openly available source 
code; in both cases, it can easily be run as an applet embedded in a web page. Here we describe the basic structure of TIM's source 
code and how to extend it, and we give examples of how we have used TIM in our own research. 
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PROGRAM SUMMARY 

Manuscript Title: TIM, a ray-tracing program for forbidden ray optics 
Authors: Dean Lambert, Alasdair C. Hamilton, George Constable, 
Harsh Snehanshu, Sharvil Talati, Johannes Courtial 
Program Title: TIM 
Journal Reference: 
Catalogue identifier: 
Licensing provisions: GNU GPL 
Programming language: Java 

Computer: Any computer capable of running the Java Virtual Machine 
(JVM) 1.6 

Operating system: Any; developed under Mac OS X Version 10.6 
RAM: typically 145 MB (interactive version running under Mac OS X 
Version 10.6) 

Keywords: ray tracing, geometrical optics, METATOYs 
Classification: 14 Graphics, 18 Optics 

External routines/libraries: JAMA [ 1 1 (source code included) 
Nature of problem: 

visualisation of scenes that include scene objects that create wave- 
optically forbidden light-ray fields 
Solution method: ray tracing 
Unusual features: 

specifically designed to visualise wave-optically forbidden light-ray 
fields; can visualise ray trajectories; can visualise geometric optic 
transformations; can create anaglyphs (for viewing with coloured "3D 
glasses") and random-dot autostereograms of the scene; integrable 
into web pages 
Running time: 

Problem-dependent; typically seconds for a simple scene 



References 



[1] JAMA: 



'Corresponding author 
E-mail address: johannes.courtial@glasgow.ac.uk 

1 Now at SUPA, School of Physics & Astronomy, University of Edinburgh, 
Edinburgh EH9 3JZ, United Kingdom. 

~HS and ST contributed while visiting from the Indian Institute of Technol- 
ogy Delhi, Hauz Khas, New Delhi 1 10 016, India. 



Java Matrix 
j avanumerics/ j ama/ 



1. Introduction 
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TIM was originally conceived as a tool to allow experimenta- 
tion (although only in the computer) with novel optical com- 
ponents called METATOYs 0] prior to building them (TIM is 
an acronym for The Interactive METATOY). Since then, it has 
developed into a much more general ray-tracing program, suit- 
able for use in optics research (including, but not limited to, 
METATOYs research), but also for simply playing with. 

METATOYs are surfaces that appear to change the direction 
of light in ways that often result in wave-optically forbidden 
light-ray fields |2|. Of course, METATOYs cannot actually cre- 
ate wave-optically forbidden light-ray fields; what they do is 
create light-ray fields that are visually almost indistinguishable 
from the forbidden fields. Of particular interest to us are sur- 
faces that perform a generalisation of refraction: they change 
the direction of transmitted light rays according to laws that 
can be much more general than Snell's law. In TIM, such gen- 
eralised refraction can be described in terms of a complex repre- 
sentation, which is explained in section|2] The ability to handle 
very general surface properties, which enables the visualisation 
of scenes that include objects with METATOY surfaces (Fig. 
[TJ, is TIM's key speciality. 

But TIM has other specialities, which support different as- 
pects of our research. TIM can 

• simulate photos taken with cameras that can focus on al- 
most arbitrary surfaces (section|3]l; 

• simulate surfaces that "teleporf" light rays to correspond- 
ing positions on other surfaces, from where the light rays 
then continue (section[4]i; 
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Figure 1: Simulated view of a cylinder lattice, seen on its own (top) and 
through a window that changes the sign of the vertical light-ray-direction com- 
ponents (bottom). 




f Edit scene ) (_ Edit view \ ( Render ) ( Save image } 



Done. Rendering took 2 s. 



Figure 2: TIM, running as an interactive Java application on an Intel MacBook. 
The central image is the rendered view of the default scene. The Java applet 
version looks identical, apart from the "Save image" button being absent in the 
Java applet version because of security restrictions. 



• visualise the trajectories of individual light rays (sec- 
tion [5}; 

• render scenes as anaglyphs for viewing with red/cyan 
anaglyph glasses (section[6]l; 

• render scenes as random-dot autostereograms (section|7]i. 

There is one more speciality: TIM can be run as an interac- 
tive Java applet (Fig. [2]), which can easily be embedded in inter- 
net page^j] We use this capability to disseminate our research 
over the internet, in a manner that invites playful exploration. 
The use of this interactive version of TIM is described in a user 
guide J3]. 

Sometimes our research requires capabilities which are not 
yet built into the interactive version of TIM. This then requires 
modification of the source code, and sometimes the modifica- 
tions become part of the interactive version of TIM. As TIM 
is open-source software, in principle everybody can do this. 
The aim of this paper is to encourage this: to invite others to 
play with the interactive version of TIM, and to entice them to 
download and modify TIM's source code. The paper contains 
several appendices aimed at facilitating the source-code modi- 
fication by outlining the implementation of ray tracing, which 
forms the core of TIM's source code ( Appendix A| i; the overall 
structure of TIM's source code (Appendix B i; and how to per- 
form a number of code-modification tasks, including rendering 
a specific scene by modifying the source code for the default 



non-interactive TIM Java application ( Appendix C I, adding a 



'An example can be found at http://www.physics.gla.ac.uk/ 
|Optics/play/TIM/| 
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Figure 3 : Representations of the normalised light-ray direction d at a point P on 
a surface, (a) Orthographic projection onto a real axis tangential to the surface 
at P and with its origin at P. The real axis lies in the plane of incidence, which 
is the plane through P that is spanned by the local surface normal, n, and the 
normalised light-ray direction, d. (b) Orthographic projection into a complex 
plane tangential to the surface at P and with its origin at P. 



new class of scene object ( Appendix D i, and adding a new class 
of surface property ( jAppendix E I. 



2. Complex representation of generalised refraction 

TIM exists because we wanted to see scenes that include 
METATOYs. Surface properties describing METATOYs there- 
fore play a key role in TIM. TIM describes almost all META- 
TOY surface properties in terms of a complex representation 
introduced in Ref . (4) . 

The complex representation is itself an extension of the way 
ray direction is represented in Snell's law, 



n sinf? = «' sin#', 



(1) 



where 6 is the angle between the incident light-ray direction 
and the surface normal at the point P where the ray intersects 
the surface, 6' is the angle between the outgoing light-ray direc- 
tion and the surface normal at P, and n and «' are the refractive 
indices that meet at P. Each sine of an angle with the local 
surface normal can be interpreted as the number at the ortho- 
graphic projection of the tip of the unit vector d representing 
the corresponding light-ray direction onto a real axis that is tan- 
gential to the surface at P, has its origin located at P, and is 
lying in the plane of incidence (the plane spanned by the inci- 
dent light-ray direction and the surface normal); this is shown 
in Fig.[3|a). Snell's law can then be interpreted as a simple mul- 
tiplication of the projection of the light-ray direction by a factor 
n/n' . 

We now replace the real axis with a complex plane (Argand 
plane), again tangential to the surface at P and with its ori- 
gin at P. Light-ray direction can then be described in terms of 
the complex number z at the orthographic projection of the tip 
of the unit light-ray-direction vector d into this complex plane 
(Fig. [3jb)). In this representation, Snell's law is still described 



by a simple multiplication of z by a factor n/n'. That the out- 
going light ray also lies in the plane of incidence is explicitly 
contained in this formulation, but not in Snell's law [4|. Ro- 
tation of the light-ray direction by an angle a around the lo- 
cal surface normal [5| is described by multiplication of z by a 
factor exp(ior) [4]. Other light-ray-direction mappings can be 
described by other complex mappings z —> z'(z); the visual ef- 
fects due to such mappings are investigated in more detail else- 
where J6). 



3. A camera that can focus on almost arbitrary surfaces 

TIM has the ability to simulate photos taken with a camera that 
can focus on almost arbitrary surfaces. In this section we ex- 
plain how TIM simulates such a camera. 

Focussing matters only in cameras with a non-zero aperture 
size. (In photos taken by cameras with a point-like aperture — 
pinhole cameras — everything is imaged as sharply as diffrac- 
tions permits.) TIM simulates a camera with a finite-size aper- 
ture by backward-tracing, starting from each pixel, a number 
of light rays which have passed through different points on the 
aperture, and averaging the resulting colours. The points on the 
aperture through which the backwards-traced light rays emerge 
are randomly chosen. Which direction these light rays have as 
they leave the aperture is determined by the imaging properties 
of the lens: the light rays originate at the position of a particular 
pixel, and so they have to leave the lens in the direction of the 
pixel's image formed by the lens. 

In a real lens, the images of all detector pixels lie, to a good 
approximation, in a plane. By allowing the images of the de- 
tector pixels to lie on a much more general surface, the focus 
surface, TIM simulates a camera which focusses on this focus 
surface. 

The focus surface is defined as follows. The camera has asso- 
ciated with it a number of scene objects that define the so-called 
focus scene, a scene in addition to the scene TIM renders. The 
focus surface is then defined as those points in the focus scene 
visible to an observer placed at the centre of the aperture. 

In the case of a thin lens, the image of any point, and specifi- 
cally any detector pixel, lies somewhere along the continuation 
of the straight line from the point to the centre of the lens. We 
generalise this here such that, in TIM's camera that focusses on 
non-planar surfaces, the image of any detector pixel lies some- 
where along the continuation of the straight line from the pixel 
position to the centre of the aperture. Fig. |4]illustrates this. 

Conveniently, the position of the image of a particular pixel 
at position P can be found using functionality already built into 
TIM, namely its capability to find the closest intersection be- 
tween an arbitrary light ray and a group of scene objects, one of 
the key capabilities for ray tracing: all that is required is finding 
the closest intersection between the focus scene and a ray that 
starts from the centre of the aperture, C, with a direction given 
by (C - P), the direction from the detector pixel to the centre of 
the aperture. 

Fig.|5]shows an example of a scene rendered for a non-planar 
focus surface. The focus scene consists of a few — but not all 
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Figure 4: Construction of the focus surface and the position of the image of 
any detector pixel. The focus surface (thick red line) consists of those parts 
of the focus scene visible from the centre C of the aperture of the imaging 
element. The position of the image of any particular detector pixel P lies on 
the intersection between the focus surface and the continuation of the straight 
line between the pixel position and the point C. The figure shows the positions 
of the images of two pixels, Pi and P2. In the example shown here, the focus 
scene consists of three objects: a circle, a rectangle, and a line. 




Figure 6: Parametrisation of a scene object. Each point on the surface 
is described by a pair of surface coordinates, in the picture the spheri- 
cal coordinates 8 and <j>, defined with respect to an arbitrary zenith di- 
rection (here (0.408,0.408,0.816)) and direction of the azimuth axis (here 
(0.913,-0.183,-0.365)). This parametrisation of the surface has been indi- 
cated by covering it in a chequerboard pattern with tiles of side length 1 in both 
6 and <j>. The local surface-coordinate axes, Bj = 3P,/<9$ and <pj = <9P,/30, to- 
gether with the local surface normals, n,, are shown for two points, P, (i = 1, 2). 
The sphere has radius 1 and is centred at (0, 0, 10). 



— of the scene objects in the scene, and a distant plane. The 
objects that are part of the focus scene can clearly be seen to be 
rendered sharply; those that are not are blurred. 




Figure 5: Example of a scene rendered with a non-planar focus surface. The 
focus scene consists of two of the four spheres, the chequered cylinder, and a 
plane in the far distance. 



4. Teleporting surface property 

An ideal lens takes the field in one plane and creates an image 
of this field in another plane. The image is stretched in the 
transverse directions, but not otherwise distorted. 

Sometimes it is desirable to create an image that is distorted 
according to a specific mapping between the coordinates in the 
object and image planes. This is called a geometrical optical 
transformation, and it can be approximated holographically [7|. 
Our own interest in geometrical optical transformations stems 
from the application of a polar-to-Cartesian transformation be- 
tween two planes to the detection of optical angular momen- 
tum QQ. 

For geometrical optical transformations, coordinates are 
clearly important. Many of TIM's scene objects have asso- 
ciated with them a two-dimensional coordinate system that 
parametrises their surface, i.e. each point P on the scene ob- 
ject's surface is described by a pair of associated surface coordi- 
nates, c\ and C2- For example, positions on a plane are described 
by Cartesian surface coordinates; positions on a circular disc 
are described by their polar coordinates r (the distance from the 
centre) and (f> (the azimuthal angle); positions on a sphere are 
described by their spherical polar coordinates 9 (the polar an- 
gle) and <p (the azimuthal angle). Scene objects parametrised in 
this way can also calculate the local surface-coordinate axes for 
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Figure 7: Simulated view through a Cartesian-to-polar converter. In the exam- 
ple shown here, the converter has been placed immediately in front of the cylin- 
der lattice shown in Fig.[T| The converter distorts vertical cylinders (green) into 
circles centred on the origin, and horizontal cylinders (blue) into radial lines. 
A brightening of the central region due to area elements being transformed to 
a different size (see Eqn J3J) is clearly visible. The converter consists of a cir- 
cular disc (the origin object), parametrised in terms of distance from the centre 
and azimuthal angle 0, with a teleporting surface whose target object is a black 
square immediately behind the disc, parametrised in terms of Cartesian coordi- 
nates. All coordinates are scaled to range from to 1 . 



any point on the surface. These are the vectors 



Cl = 



dP_ 

dc\ 



C2 = 



dP_ 

dC2 ' 



(2) 



they respectively point in the direction in which the correspond- 
ing surface coordinate changes at the point P, and their respec- 
tive length indicates the distance on the surface over which the 
corresponding surface coordinate changes by 1. Fig. [6] shows 
the local surface-coordinate axes for two positions on a sphere. 
The surface coordinates and surface-coordinate axes, respec- 
tively, play a key role in the calculation of the starting point and 
direction of the continuation of the incident light ray. 

TIM can simulate geometrical optical transformations using 
an unusual surface property. In TIM's implementation of ray 



tracing (see Appendix A i, surface properties are responsible 
for returning the colour of light leaving a specific point on the 
surface in a specific direction. Finding this colour often requires 
further tracing of the incident ray, for example in the case of a 
specularly reflective surface, where the continuation of the ray 
leaves the same point on the surface with a new direction given 
by the law of reflection. Geometrical optical transformations 
can therefore be implemented in the form of a surface prop- 
erty that continues tracing the incident light ray, starting from a 
transformed position and with a suitably transformed direction. 

TIM's teleporting surface property does precisely this. A 
teleporting surface has associated with it a destination object; 
note that the link is one-way. We call the object with the tele- 
porting surface the origin object. The mapping from the po- 
sition P where the incident light ray intersects the origin ob- 
ject to the position where its continuation leaves the destina- 



tion object's surface, P', is defined in terms of the surface- 
coordinate systems (Fig. [6} associated with the two objects' 
surfaces. Specifically, if the position P where the incident light 
ray intersects the origin object's surface is described by some 
values of its surface coordinates, then the point P' where the 
ray's continuation leaves the destination object's surface is the 
point at which the destination object's surface coordinates take 
those same values. For example, if a planar origin object is 
parametrised in terms of polar surface coordinates r and <p, 
and the destination object associated with its teleporting sur- 
face property is also planar and parametrised in terms of Carte- 
sian surface coordinates, then this setup is a polar-to-Cartesian 
converter for backwards-propagating light rays, which means it 
is a Cartesian-to-polar converter for forwards-propagating light 
rays. Fig.|7]shows a three-dimensional (3D) lattice of cylinders 
seen through such a setup. It can clearly be seen that lines of 
constant z and x value (i.e. vertical lines) in the cylinder lattice 
become lines of constant radius (i.e. circles) when seen through 
the converter, and that lines of constant z and y value (horizontal 
lines) become lines of constant azimuthal angle (spokes). 

The corresponding mapping of the light-ray direction is 
based on wave -optical considerations. Specifically, we assume 
that phase and intensity of the (scalar) optical field on the tele- 
porting surface gets mapped onto the destination object's sur- 
face. In the ray-optics limit of wave optics J9), which is ar- 
guably appropriate here, the light-ray direction is proportional 
to the direction of the gradient of the phase. The wave's lo- 
cal phase gradient then defines the new light-ray direction. In 
TIM, light-ray direction is normalised and therefore naturally 
interpreted as normalised phase gradient. 

The components of the phase gradient are, of course, the rate 
of change of phase in the corresponding directions. Consider 
the two coordinate systems that describe the surfaces of the ori- 
gin object and of the destination object. Now consider the com- 
ponent of the incident light-ray direction in the direction of the 
origin object's first surface coordinate, c\. A value g\ means 
that the phase changes locally at a rate of g\ full 2n phase cy- 
cles over the distance on the surface in which c\ changes by 
1. On the destination object, the phase then changes locally 
(at the point P' where the light ray continues) at a rate of g\ 
full 2tt phase cycles over the distance in which the destination 
object's first surface coordinate, c' v changes by 1. The ratio 
of the phase gradients in the direction of the first surface co- 
ordinate, which is the ratio of the light-ray components in the 
direction of the first surface coordinates, is therefore given by 
the ratio of the distances over which the first surface coordinate 
changes by 1 in the origin object and in the destination object. 
These distances are given by length of surface-coordinate axes, 
|c 1 1 — |3P/3ci| and |c'j| = \dP' /dc^. A similar argument can be 
made for the second surface coordinate, c-i- The components of 
the direction of the continuation of the light ray in the directions 
of the destination object's first and second surface coordinates, 
d\ and d' 2 , are then 



ICll 



CL'r, 



(3) 



where d\ and do are the components of the direction of the in- 
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cident light ray in the directions of the first and second surface 
coordinates of the origin object. 

The component of the light-ray-direction vector in the direc- 
tion of the surface normal is chosen such that the length of the 
light-ray-direction vector remains unchanged. This correctly 
represents the case of the continuation of the ray travelling in a 
medium with the same refractive index as the medium in which 
the incident ray was travelling. 

One further consideration is a concomitant change in bright- 
ness. TIM assumes that no power is lost during teleportation, 
so the power entering an area element dA on the surface of the 
origin object at position P is the same as that exiting the cor- 
responding area element dA' on the surface of the destination 
object at P' . The light intensities (power per area) at P and P', 
I and /', are then given by the equation IdA = /'dA'. The ratio 
of the area elements is given by 

dA' |c', x c' I 

= — -, (4) 

dA |cixc 2 [' 

and so 

I = I'\^-?\. (5) 
|Ci xc 2 | 

It is worth noting that the teleporting surface property can be 
used for purposes other than implementing geometrical optical 
transformations. For example, consider a planar origin object 
placed immediately in front of the camera and a planar target 
object placed elsewhere, both parametrised in terms of Carte- 
sian coordinate systems. If the scale of the two coordinate sys- 
tems is the same, i.e. if the surface-coordinate axes on the ori- 
gin and target objects are of the same length, then the effect is a 
simple change of camera position and viewing direction. 

5. Visualisation of light-ray trajectories 

One of TIM's capabilities, namely the visualisation of light-ray 
trajectories, can be very helpful in understanding the effect of 
optical components. Fig. [8] shows a cone of light rays being 
traced through a window that rotates the local light-ray direc- 
tion through 90°, showing, for example, that such a window 
would not create an image of a point light source at the apex of 
the cone. 

TIM visualises the trajectories of specific light rays in three 
steps: 

1 . trace the light rays, keeping a list of the points where each 
light ray intersects a scene object; 

2. for each segment of the above light-ray trajectory, i.e. be- 
tween each pair of neighbouring intersection points, add a 
cylinder to the scene; 

3. visualise the scene. 

The first point uses the ray-tracing methods already built into 
TIM, but those methods needed to be extended slightly to keep 
track of ray trajectories. This requires the ability to deal with 
rays branching, which occurs whenever a ray encounters an 
object with multiple surface properties that require further ray 




Figure 8: Visualisation of light-ray trajectories. A cone of light-ray trajectories 
originating from a point in front of a window that rotates the light-ray direction 
by 150° around the local window normal is converted into a twisted bundle of 
rays. 

tracing, such as a partially transmissive mirror. In TIM, when- 
ever a ray hits a surface that requires further ray tracing, a new 
ray is created, added to the list of the ray's branches, and traced. 
A light ray's full trajectory is then stored in the form of a list of 
positions where the main branch intersects scene objects, and 
the list of the branches. 

6. Anaglyphs 

Parallax causes a scene to look different when viewed from two 
different positions. This is called binocular disparity; the pro- 
cess of deriving depth perception from the two different views 
the two eyes receive is called stereopsis [10|. In anaglyph 
images IfTTI . the two views are superposed, but in different 
colours. When viewed through suitable anaglyph glasses, i.e. 
a different colour filter in front of each eye which in the sim- 
plest case completely filters out the view intended for the other 
eye, different images can be presented to the eyes, and stereop- 
sis can lead to depth perception. 

TIM can create anaglyph images intended for viewing with 
red/cyan anaglyph glasses. Two images are calculated for cam- 
era positions that differ by a sideways displacement. These two 
images can then be turned into anaglyph images in two different 
ways: 

1. The red component of the image is the luminosity of the 
left-eye image, the blue component is the luminosity of the 
right-eye image. The resulting anaglyph has lost colour 
information. 

2. Following "recent simple practice" [11|, the blue and 
green components are removed from the image that corre- 
sponds to the left eye, the red component is removed from 
the right-eye image, and the two images are superposed. 
The resulting anaglyph includes colour information, but 
does not work very well for objects of certain colours. 
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Figure 9: Anaglyph versions of the images in Fig. [T] which show a cylinder 
lattice au naturel (top) and when seen through a window that inverts the vertical 
ray-direction component (bottom). 




Figure 10: Example of a colour anaglyph image. In addition to the chequer- 
board floor, the scene contains three reflective spheres. 



Figures |9| and [TO] show examples of anaglyph images. 



7. Random-dot autostereograms 

TIM can render scenes as random-dot autostereograms [12|. 



Fig. 1 1 shows an example of such a random-dot autostereogram 



created by TIM. 

Autostereograms rely on the fact that two different patterned 
surfaces can look identical from different viewing positions. In 
the case of standard autostereograms, the two different view- 
ing positions are the positions of the observer's eyes, one of the 
surfaces is planar, and the pattern in that plane is the autostere- 
ogram of the other, three-dimensional, surface. For the observer 
to perceive the visual illusion of seeing the three-dimensional 
surface when viewing the autostereogram requires the patterns 
to be sufficiently detailed. 

Placing dots on the two surfaces such that the patterns are 
consistent with each other is perhaps the simplest way to con- 
struct autostereograms. TIM uses the following algorithm. 
We call the plane of the autostereogram A, and the three- 



dimensional surface S (see Fig. 12 1 



1 . Randomly pick a dot colour. 

2. Randomly pick a position D in the plane A and place a 
small dot of the picked dot colour there. 

3. Find the point P on S that lies on the same line of sight 
as D, as seen from the position of the left eye, L. For 
the surfaces A and S to look identical from the position of 
the left eye, P therefore has to have the same colour as D, 
namely the dot colour picked above. 

4. Find the point D' on A that lies on the same line of sight 
as P, as seen from the position of the right eye, R. By the 
same argument as above, the colour of this point must also 
be the dot colour picked above. Therefore, place another 
small dot of the picked dot colour at D'. 
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Figure 11: Random-dot autostereogram of TIM's default scene (Fig.[2). Note 
that the scene includes a plane behind Tim's head which can be seen in the 
background, making it easier to see the autostereogram. 
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Figure 12: Principle of random-dot autostereograms. The eyes are located at 
the positions L and R; the autostereogram is in the plane A; S is the 3D surface 
represented by the autostereogram. 



5. The previous two steps constructed, from the position D of 
one dot in the autostereogram, the position D' of another 
dot that has to have the same colour. Repeat the previous 
two steps to construct, from the position D' of this other 
dot, the position of yet another dot that has to have the 
same colour. Keep repeating until the position of the new 
dot lies outside the area of the autostereogram. 

6. Steps[3]to[5]constructed, from the position D picked in step 
[2] the positions of further dots that have to be of the same 
colour. This was done by using the left eye's line of sight 
to construct a corresponding point on S , and then the right 
eye's line of sight to construct a point on A corresponding 
to this new point. Start again from the position picked in 
step |2j D, and repeat steps [3] to [5] but swapping the role 
of the left eye and the right eye. In other words, now use 
the right eye's line of sight to construct a point on S that 
corresponds to a dot position in A, and then use the left 
eye's line of sight to construct a point on A corresponding 
to this point on S , which is then the position of a new dot. 

Two details in TIM's algorithm are perhaps worth noting. 

1 . The dots placed by TIM in the autostereogram are not sin- 
gle pixels but Gaussians. This means that their positions 
are not restricted to the pixel positions, so they can be 
placed "between pixels". This is advantageous as restrict- 
ing dot positions to pixel positions restricts the possible 
separations between dots, and therefore the depths the dot 
patterns can represent, which results in "layered" random- 
dot stereograms. 

2. Each dot TIM places in the autostereogram has a partic- 
ular hue. To calculate the colour of a particular pixel in 
the autostereogram, TIM calculates the weighted average 
of the hues of all the dots that intersect at the pixel. Hue 
is the azimuthal angle <p of a colour's position in a suitable 
colour wheel (e.g. red = 0°, yellow = 60°, green = 120°, 
cyan = 180°, blue = 240°, purple = 300°). To form the 
weighted average of the hues due to all dots, TIM converts 
the hue of each dot into corresponding Cartesian coordi- 
nates (the coordinates corresponding to the hue <f>j of the 
jth dot, weighted by a factor wj, are Xj ■ — wj cos(<pj) and 
y j = Wj sin(0j)), adding up the x and y coordinates due 
to all hues, and calculating the azimuthal angle <p of the 
resulting (x, y) position. The weight of the hue of a par- 
ticular dot is given by Wj = exp [-(r,/p) 2 ], where rj is the 
distance between the pixel and the centre of the jth dot, 
and p is the dot radius. This can be expressed in terms of 
complex numbers as 

(/> = arg |^ exp [-(^/p) 2 ] exp(i^)| . (6) 

Finally, the pixel colour is found using the standard Java 
method for converting a colour represented in terms of its 
hue, saturation and brightness (HSB) into its red, green 
and blue (RGB) components. Both saturation and bright- 
ness are set to their maximum value, 1 . 
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8. Conclusions 

TIM is a powerful raytracer with extensive capabilities, a num- 
ber of them unique. We use TIM in our research on META- 
TOYs: for disseminating our research over the internet by invit- 
ing playful experimentation with METATOYs through TIM's 
interactive version; and for conducting computer experiments 
with METATOYs ourselves. 

Sometimes it is necessary to modify TIM's source code, 
which can be a daunting prospect. This paper is intended to 
help others and ourselves doing this. We hope it will entice 
other researchers to use TIM in their own work. 
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Appendix A. Implementation of ray tracing in TIM 

TIM is written in Java IfPJI . an object-orientated programming 
language [ 14]. As in all object-orientated languages, objects are 
instances of classes. A class has associated methods and data 
(variables), which take on specific values in specific instances 
of the class, i.e. the objects. A class can have subclasses, which 
inherit its methods and properties^] the former is called the lat- 
ter's superclass. In Java there are also interfaces, which are 
collections of methods. If an object implements a specific in- 
terface, it has to implement all the interface's methods. 

To trace a ray in TIM, a number of objects are interacting. 
The following are the most important ones. 

Rays. Each ray is an object of class Ray, which has a starting 
position and a normalised direction, both represented as 
3D Cartesian vectors. 

Scene objects. Each scene object implements the interface 
SceneObjectJ^J most (but, for complicated reasons, not 
all) are instances of a subclass of SceneObjectClass, 
which implements the SceneObject interface. Specifi- 
cally, a scene object implements methods that calculate 
the intersection point between the scene object and 
any ray, and methods that calculate the colour of an 
intersection point when seen along the direction of a 
given ray and under specified illumination. There are 
particularly fundamental scene objects, each typically rep- 
resenting a simple geometrical object (such as a sphere) 
with specific surface properties (such as reflective), 
which are instances of the SceneObjectPrimitive 
subclass of SceneObjectClass. Another subclass 
of SceneObjectClass is SceneObjectContainer, 
which represents a collection of scene objects. 
There are also more complicated scene objects 



2 Unless they prevent this specifically by explicitly overriding individual 
methods and/or properties. 

3 Note that every Java class is a subclass of the Object class. 



that are neither SceneObjectPrimitives nor 
SceneObjectContainers, but ultimately every in- 
tersection with a SceneObject must be traceable to an 
intersection with a SceneObjectPrimitive. 

Surface properties. Perhaps the simplest surface property is 
a colour that is independent of any light sources (ef- 
fectively a coloured glow), which is represented by the 
class Surf aceColourLightSourcelndependent. The 
colour of non-glowing surfaces depends on illumination, 
and this is represented by the class Surf aceColour, 
in which the surface has separate diffuse and specular 
colours. The diffuse component colours light due to Lam- 
bertian reflectance [151; the specular components colours 
light that is specularly (or near-specularly) reflected |[T6l . 

There are also classes representing surfaces on which the 
ray does not end, but which change its direction. Exam- 
ples include mirror surfaces (Reflective) and refractive- 
index interfaces (Refractive). 

Finally, there is currently one class (Teleporting) which 
continues tracing a light ray with a changed direction and 
from a new starting position. 

All surface properties implement the interface 
Surf aceProperty. 

Light sources. Light sources are represented by instances of 
the class LightSource. In TIM, two types of light source 
are implemented: ambient light, represented by the class 
AmbientLight, and light sources with a specific 3D posi- 
tion which throw shadows and which can create highlights 
due to specular (or near-specular) reflection off surfaces of 
type Surf aceColour. 

Ray-tracing software usually considers only those light rays 
that eventually enter the virtual camera. They do this by tracing 
light rays backwards, starting from each pixel in the camera's 
virtual detector chip. What they try to do is establish the colour 
such a light ray would have if it was travelling in the opposite 
direction, i.e. the colour of the reverse ray, which is the colour 
an observer would see in the direction of the light ray. More 
details can be found in Ref . IfTTI . 

Backwards tracing a specific light ray in TIM proceeds as 
follows: 

1. The SceneObject representing the entire scene is asked 
to return the colour of the reverse ray. 

2. The SceneObject finds the SceneObjectPrimitive 
the light ray intersects (if any), and asks its 
Surf aceProperty to return the colour of the reverse ray. 

3. The Surf aceProperty either changes the light-ray direc- 
tion and starts tracing again, or it determines the colour of 
the surface under illumination by the LightSource. If the 
Surf aceProperty is a Surf acePropertyContainer, 
then the colours due to all the surface properties are 
summed (by adding up the individual RGB components). 

4. The LightSource returns a colour according to 
its shading model. If the LightSource is a 
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LightSourceContainer, then it asks each of the 
LightSources it contains to return a colour and then sums 
these colours. 

We discuss the steps in some more detail below. 

In TIM, tracing an individual ray backwards is initiated 
by asking the SceneObjectContainer containing all scene 
objects to return the colour an observer at the ray's start- 
ing point would see in the ray's direction. This is done 
by calling the SceneObjectContainer's getColour method 
(which is defined in the SceneObjectContainer's superclass 
SceneObjectClass). The SceneObjectContainer then es- 
tablishes which one (if any) of the scene objects it contains the 
ray would intersect with first. If the ray intersects none of the 
scene objects, then the getColour method returns the colour 
black. If the ray intersects one of the scene objects, then the 
method establishes which SceneObjectPrimitive was hit 
and calls this SceneObjectPrimitive's Surf aceProperty 
to establish the colour. 

Each Surf aceProperty implements a getColour 
method, which returns the colour an observer at the 
ray's starting point would see in the ray's direc- 
tion. In the simplest case, implemented in the class 
Surf aceColourLightSourcelndependent (surface type 
"Coloured (glowing)"), the colour stored within the specific 
instance of the class is returned, irrespective of the illumination 
and the rest of the scene. Illumination-dependent colour is 
handled by the Surf aceColour class, which calls the light 
source's getColour method to establish the appearance of 
the surface under illumination by the light source. There 
are also surface properties, for example Reflective, whose 
getColour method returns the colour resulting from tracing 
through the scene a new ray that starts from the intersection 
point and travels in a new direction (given, in the case of the 
Reflective class, by the law of reflection). Finally, it is also 
possible to have surface properties whose getColour method 
returns the colour resulting from tracing a new ray that starts at 
a point different from the intersection point; the Teleporting 
class is an example of such a class. In the latter two cases of 
surface properties that continue tracing rays through the optical 
system, the colour may be slightly darkened to represent a 
reflection or transmission coefficient of less than one. 

A light source's getColour method calculates the colour 
in which an observer would see a specific surface colour at 
a particular point on a surface if it was illuminated only by 
this light source. TIM models two different types of light 
source: ambient light (class AmbientLight), which illumi- 
nates all objects in all directions with a given RGB colour; 
and PhongLightSource, which implements the Phong shad- 
ing model fl6l . The latter corresponds roughly to a small, 
coloured light bulb: it has a specific position, which is used 
to determine whether the surface is in another scene object's 
shadow and whether near-specular reflection occurs, which 
leads to highlights; and it has a specific colour. There is also a 
class (LightSourceContainer) that models the effect of com- 
binations of different light sources. 

It should be clear from the above discussion that 



backward tracing of a ray ends when a light ray 
has intersected a surface with a surface of class 
Surf aceColourLightSourcelndependent, or when it 
hits a surface of class Surf aceColour (in which case the light 
source performs the final calculation of colour). Sometimes it 
can happen that rays get "trapped", for example between mirror 
surfaces such as those in canonical optical resonators |18|. 
In such cases, a reflection (or transmission) coefficient < 1 
ensures exponential fall-off of the intensity with the number 
of bounces, so such light rays become dark. TIM limits the 
number of bounces it models, and when the limit is reached 
returns the colour black. This is controlled by a variable called 
traceLevel, which gets passed between the objects. The 
backwards tracing process starts with traceLevel taking a 
value of typically 100; whenever a surface property initiates 
tracing of a new ray, it does so with a value of traceLevel 
that is reduced by 1 . When the value is reached, the colour 
black is returned. 

Appendix B. Source-code structure 

TIM is divided into a hierarchical package structure. We 
describe here the main branch of this structure, namely the 
optics package and the packages it contains. There are three 
additional packages: 

1. JAMA is a matrix package in the public domain 1191 . TIM 
uses it; for convenience, the unmodified third-party source 
code is distributed with TIM's source code. 

2. math is a package that defines additional mathematical 
functionality as required, including classes dealing with 
complex numbers, 2D vectors, and 3D vectors. 

3. test contains only the class Test, which can be executed 
as a Java application for the purposes of testing any parts 
of the code. 

Appendix B.l. The optics package 

The optics package collects together optics-related code. At 
the top level, it contains the Constants class, a collection of 
optics-related constants such as a few common refractive in- 
dices; and DoubleColour, which is used internally to represent 
colours. 

The only sub-package within the optics package that is 
distributed with TIM's source code is optics . raytrace. It 
contains both the ray tracer code as well as associated math- 
ematical, graphical and user interface code, organised in the 
form of a number of sub-packages. At the top level, it 
contains NonlnteractiveTIM, a template for a class that 
can be run as a Java application that uses TIM (see sec- 
tion Appendix C I; TIMApplet, the applet class that is called 



when the interactive version of TIM is run as an applet; 
TIMJavaApplication, which allows the interactive version of 
TIM to be run as a Java application (with slightly increased 
functionality, specifically the ability to save images as .bmp 
files); and TIMInteractiveBits, a class that defines the in- 
teractive parts of TIM, which are called by both the TIMApplet 
and TIMJavaApplication classes. 
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The package optics .raytrace . core contains a number 
of the core ray -tracing classes and interfaces. A number 



of these, and their interactions, are discussed in Appendix 



|A| The ray-tracing core classes and interfaces include 
those defining the structure of cameras (Camera), light 
sources (LightSource; see optics . raytrace . lights for 
implementations), scene objects (SceneObject; implemen- 
tations are in package optics . raytrace . sceneObjects), 
surface properties (Surf aceProperty; implementa- 
tions in optics . raytrace . surf aces), rays (Ray and 
RayWithTrajectory), and intersections between rays and 
objects (RaySceneObjectlntersection). The Studio 
class defines a collection of everything required to calculate a 
photo, namely information about the scene (in a SceneObject 
object), lighting (a LightSource object), and camera (in the 
form of a Camera object; implementations of cameras are 
in the package optics . raytrace . cameras). A number of 
interfaces outline mechanisms for the parametrisation of object 
surfaces: 

• ParametrisedObject defines coordinates assigned to 
each point on a surface; 

• 0ne20neParametrised0bject extends 
ParametrisedObject by asking for the reverse of 
the coordinate assignment, i.e. for a method that returns 
the point on a surface associated with a set of coordinate 
values. 

Other classes included in the package are CameraClass, 
which implements a number of methods common to cur- 
rently all cameras, and which is a superclass to currently 
all cameras; SceneObjectClass, which similarly im- 
plements a number of methods common to most scene 
objects, and is a superclass of many scene-object classes; 
SceneObjectPrimitive, which describes simple geometric 
objects, such as spheres and planes; CCD and CentredCCD, 
which represent the light-detecting element in cameras; 
Transformation, which defines the structure of geometrical 
transformations (such as translation or rotation) which can 
be applied to scene objects (for implementations see package 
optics . raytrace . sceneObjects . transformations); 
and DoubleColourCamera and DoubleColourCCD, which 
define the structure of higher-quality cameras and their 
light-detecting elements. 

The useful optics . raytrace . demo package contains a 
number of classes which can be run as Java applications and 
which demonstrate the use and effect of different features, for 



example LightsDemo, which was used to create Fig. B.13 It 
is worth studying the examples contained in this package to un- 
derstand how to access TIM's functionality. 

The package optics .raytrace . exceptions defines 
classes that signal exceptional circumstances that occured 
during rendering, for example a ray becoming evanescent 
(EvanescentException). 

Appendix B.2. optics .raytrace. cameras 
The optics .raytrace . cameras package contains imple- 
mentations of the Camera interface. These handle the 




Figure B.13: Effect of combination of different light sources. Here, a shiny 
blue sphere is illuminated by a combination of three Phong light sources, one 
red, one green, one blue, placed in different directions high above the sphere. 
The Phong light sources produce differently-coloured highlights at the top of 
the sphere and differently-coloured shadows (the colours are due to subtrac- 
tive colour mixing) on the floor. Where the shadows from all Phong light 
sources overlap, the scene is completely black in the absence of an ambient 
light source. The image was rendered using the LightsDemo class in the 
optics . raytrace . demo package I Appendix B) . 



mechanisms of generating the rays that are then traced 
through the scene, and of turning creating corresponding im- 
ages. Implemented camera classes include PinholeCamera, 
which is the simplest type of camera that takes pictures in 
which everything is in focus; ApertureCamera, a camera 
with a circular aperture that can focus on any transverse 
plane; AnyFocusSurf aceCamera, a camera with a circu- 
lar aperture that can focus very general surfaces (section [3]); 
OrthographicCamera, which produces orthographic projec- 
tions into a plane; AnaglyphCamera, which can produce ei- 
ther red/blue or colour anaglyph images that can be viewed 
with standard red/cyan anaglyph glasses (section [6]); and 
AutostereogramCamera, which can create random-dot au- 
tostereograms of the scene (section|7|. 

Appendix B.3. optics .ray trace, lights 

The optics . raytrace . lights package includes implemen- 
tations of light sources. These include AmbientLight, which 
represents a coloured ambient light; PhongLightSource, 
which realizes the Phong shading model 0161 . which is 
roughly equivalent to a slightly fuzzy point light source; and 
LightSourceContainer, which allows light sources to be 



combined. Fig. B.13 demonstrates effects due to different light 
sources. 

Appendix B.4. optics .raytrace . sceneObjects 

The package optics . raytrace . sceneOb j ects contains im- 
plementations of scene objects. It contains classes describing 
different types of scene objects: 
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Simple geometrical shapes. Classes that describe sim- 
ple geometrical shapes are implementations of the 

Ex- 



SceneObjectPrimitive class (Appendix D.l 



amples include spheres (Sphere), planes (Plane), 
parallelograms (CentredParallelogram), discs (Disc), 
and cylinders (Cylinder). 

Combinations of other scene objects. A number of classes 
describe compound objects (Appendix D.2i. Examples 



include Arrow, Cylinder, and Eye. 

Shapes with parametrised surfaces. Parametrisation, 

described by implementations of the 
interfaces ParametrisedObject and 

0ne20neParametrised0bject, assigns coordi- 
nates to points on the surface of a geometrical 
shape (Appendix D.3 1. Examples of classes that 
define parametrised geometrical shapes include 
ParametrisedSphere, ParametrisedPlane, and 
ParametrisedCentredParallelogram. There are 
also classes that allow the range of the coordinates that 
describes the surface of the geometrical shape to be varied. 
For example, in the ScaledParametrisedSphere class, 
the range of the polar angle 6 can be set to range from 
an arbitrary value # m j n to another arbitrary value # max . 
Other examples include ScaledParametrisedDisc and 
ScaledParametrisedCentredParallelogram. 

The optics . raytrace . sceneOb j ects . solidGeometry 
package is a collection of classes useful for combining 
scene objects. In the simplest case, scene objects are 
grouped in a hierarchical way (SceneOb jectContainer). 
More elaborate combinations of scene objects include 
intersections (SceneOb jectlntersection), unions 
(SceneOb jectUnion), and inverse (SceneObjectlnverse). 

One of the capabilities required of any scene object is the 
ability to create a transformed copy of itself. The structure 
of the transformation is defined by the Transformation 
class (in optics . raytrace . core). The package 

optics . raytrace . sceneObj ects . transformations 
contains classes that describe specific types of trans- 
formation, i.e. subclasses of Transformation. Ex- 
amples include Translation, RotationAroundXAxis, 
RotationAroundYAxis, RotationAroundZAxis, and the 
more general LinearTransf ormation. 

Appendix B.5. optics .raytrace. surf aces 
The optics . raytrace . surf aces package contains im- 
plementations of the Surf aceProperty interface (in 
optics . raytrace . core). These include 

• the classes representing coloured surfaces, 
Surf aceColourLightSourcelndependent and 
Surf aceColour; 

• a class representing a transparent surface (Transparent); 

• the Reflective class which represents specularly reflec- 
tive surfaces; 



• the Refractive class which represents refraction at the 
interface between media with different refractive indices 
according to Snell's law; 

• a class that facilitates the implementation of classes that 
represent surfaces that change direction according to gen- 
eralised laws of refraction (Metaref ractive); 

• a number of subclasses of Metaref ractive represent- 
ing surfaces that invert of one of the ray-direction com- 
ponents tangential to the surface [20 1 (RayFlipping), ro- 
tate the ray direction around the local surface normal [5| 
(RayRotating), and refract like — formally [4| — the 
interface between media with a complex refractive-index 
ratio would (Ref ractiveComplex); 

• classes representing surfaces that have combinations of 
other surface properties (Surf acePropertyContainer 
and Surf acePropertyContainerWeighted); 

• a SemiTransparent class, which combines an arbitrary 
surface property with the Transparent surface property; 

• a class representing a surface whose inside has different 
properties from its outside (TwoSidedSurf ace); 

• classes representing surfaces with completely dif- 
ferent surface properties at different points on 
the surface (Surf aceTiling, EitherOrSurf ace, 
PictureSurf ace, PictureSurf aceDif f use, 
PictureSurf aceSpecular; 

• a class representing the hologram of a thin lens 
(ThinLensHologram), which changes light-ray direction 
dependent on the point where it is being intersected; 

• and a class representing a surface a light ray enters and 
then continues, from a corresponding position and with 
a corresponding direction, from the surface of a different 
scene object (Teleporting — see section|4j we use this 
to model geometric optical transformations |8|). 



Appendix E.l discusses how to add new surface properties to 
TIM. 

The optics .raytrace . surfaces .metaref raction 
package contains description of the direction change 
performed by surfaces of class Metaref ractive (see 
optics .raytrace . surf aces). The format of these de- 
scriptions is defined by the abstract Metaref raction 
class. The ComplexMetaref raction class is a subclass 
of Metaref raction, again abstract, which formulates the 
direction change in terms of the projections of the incoming 
and outgoing light rays into an Argand plane tangential to the 
surface at the intersection point and with its origin there (sec- 
tion [2J [6]. This is a generalisation of the formal description 
in terms of multiplication with a complex number of rotation 
of the light-ray direction around the local surface normal |4|. 
All other classes in this package are non-abstract subclasses of 
ComplexMetaref raction. They include classes that describe 
surfaces that change light-ray direction described by complex 
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Figure B.14: Editing one object in a hierarchical structure using the IPanel 
class. The top line displays a breadcrumb trail, giving an idea of the place in 
the hierarchy. 



multiplication (ComplexMetaref ractionMultiplication), 
complex addition (ComplexMetaref ractionAddition), 
complex conjugation (ComplexMetaref ractionCC), and 
complex exponentiation (ComplexMetaref ractionExp). 

Appendix B.6. optics, raytrace. GUI 
The optics . raytrace . GUI package is a collection of 
packages that together constitute TIM's graphical user 
interface (GUI). All but one of the sub-packages of 
optics . raytrace . GUI contain classes that handle user inter- 
action in TIM's interactive version. 

The exception that contains the classes that handle user in- 
teraction in the non-interactive version of TIM is the package 
optics . raytrace . GUI .nonlnteractive. It contains two 
classes: PhotoCanvas, which creates a panel (screen element) 
in which NonlnteractiveTIM and classes derived from it dis- 
play the rendered image; and PhotoFrame, which opens a win- 
dow containing a PhotoCanvas. 

The package optics . raytrace . GUI . core contains GUI 
core classes. The RaytraceWorker class handles rendering 
in a background thread, so that the GUI can continue to react 
to user interaction. The class IPanel defines a screen element 
intended to allow browsing and editing hierarchical networks of 
objects on a relatively small screen area, so that it can be inte- 
grated into an internet page without necessarily dominating the 
page. At any one time, the panel corresponding to one object 
in this network is displayed. IPanel handles a stack of these 
panels, displaying only the top one, and a breadcrumb trail of 



the other panels in the stack (Fig. B. 14 1. The mechanism by 



which this panel is supplied by the object, and how control is 



handed over when another object's panel gets displayed in the 
IPanel, is defined in the IPanelComponent interface, which 
all objects in TIM which are editable interactively implement. 
EditableCamera is an interface that defines the functionality 
of an editable camera. 

The package optics . raytrace . GUI . lowLevel is a 
collection of low-level classes related to the GUI. The class 
GUIFrame represents the window TIM's interactive version 
opens when run as a Java application. GUIPanel is the 
top-level screen element that contains the entire GUI, i.e. 
the tabs showing views of the rendered scene from dif- 
ferent view points, any component being edited, and all 
buttons (see Fig. [2J. Buf f eredlmageCanvas is the panel 
displaying the rendered image. RaytracinglmageCanvas 
extends Buf f eredlmageCanvas by adding some inter- 
active functionality, including the ability to identify the 
scene object and coordinates of the point on the object the 
mouse pointer hovers over and clicks on, and the ability 
to edit that scene object by double-clicking on it. Most 
classes provide panels for editing small chunks of data, 
including integers (IntPanel and LabelledlntPanel, 
an IntPanel displayed next to a brief verbal description), 
individual double-precision real numbers (DoublePanel and 
LabelledDoublePanel), pairs of double-precision real num- 
bers (TwoNumbersPanel), complex numbers (ComplexPanel 
and LabelledComplexPanel), 2D vectors (Vector2DPanel 
and LabelledVector2DPanel), 3D vectors (Vector3DPanel 
and LabelledVector3DPanel), and the limiting values of 
a range of real numbers (LabelledMinMaxPanel). The 
class SceneObjectPrimitivesComboBox describes a panel 
that allows any SceneObjectPrimitive in the scene to be 
selected, which is used in the panel editing surface properties 
for selecting a target object for a surface of type Teleporting. 
There are a number of classes for editing camera-specific pa- 
rameters such as aperture size (ApertureSizeComboBox 
and LabelledApertureSizeComboBox); quality 
(QualityComboBox and LabelledQualityComboBox), 
which can be applied to blurring and to anti-aliasing; and 
all parameters related to camera blur collected in one panel 
(BlurPanel). The class ButtonsPanel describes a panel con- 
taining one or more buttons. The interface Statuslndicator 
outlines the structure of an object that can display brief status 
messages. Finally, GUIBitsAndBobs is a small collection of 
miscellaneous methods commonly used by the GUI. 

The package optics . raytrace . GUI . cameras con- 
tains classes that describe various editable camera 
classes. The classes EditableAnyForucSurf aceCamera, 
EditableApertureCamera, EditableAnaglyphCamera, 
EditableAutostereogramCamera and 
EditableOrthographicCamera respectively extend 
the AnyFocusSurf aceCamera, ApertureCamera, 
AnaglyphCamera, AutostereogramCamera and 

OrthographicCamera classes in this way. The 
classes EditableOrthographicCameraSide and 
EditableOrthographicCameraTop make special cases 
of the OrthographicCamera class editable; these respectively 
correspond to TIM's "Side view" and "Top view" tabs. 
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The package optics . raytrace . GUI . sceneObjects 
contains the classes describing all editable scene ob- 
jects. Most of these are simply editable versions of 
classes in optics .raytrace . sceneObjects, includ- 
ing EditableArrow, EditableParametrisedCone, 
EditableParametrisedCylinder, 
EditableParametrisedPlane, 

EditableRayTraj ectory, EditableRayTraj ectoryCone, 
EditableScaledParametrisedDisc, 
EditableScaledParametrisedCentredParallelogram, 
and EditableScaledParametrisedSphere. The 
class EditableSceneObjectCollection allows edit- 
ing of groups of scene objects, which can be com- 
bined a number of ways respectively handled by the 
SceneObjectContainer, SceneObject Inter sect ion, 
and SceneObjectUnion classes in the 
optics . raytrace . sceneOb j ects . solidGeometry 
package. A few of the classes defined in 

optics . raytrace . GUI . sceneOb j ects ex- 
ist only in editable form. Examples include 
EditableCylinderFrame, Edit ableCylinderLatt ice, 
EditableLens, EditableOb j ectCoordinateSystem, 
EditablePolarToCartesianConverter, and 
EditableTelescope. 

The optics . raytrace . GUI . surf aces package con- 
tains classes that enable selecting a class of surface 
property and editing class-specific parameters. The 
class that provides a panel for doing all of this is 



Surf acePropertyPanel (see Fig. E.15 appendix Appendix 



E.3 1. The remaining classes in this package allow editing 
of class-specific parameters. EditableSurf aceTiling 
and EditableTwoSidedSurf ace are editable sub- 
classes of Surf aceTiling and TwoSidedSurf ace, 
respectively. TeleportingTargetsComboBox is a sub- 
class of SceneObjectPrimitivesComboBox (in the 
optics . raytrace . GUI . lowLevel package) that allows 
a suitable scene object contained in the scene to be selected. In 
its labelled form (LabelledTeleportingTargetsComboBox) 
this is used in the Surf acePropertyPanel class to select a 
target object for the Teleporting surface property. 

Last, and least, the package 

optics . raytrace . GUI . sceneObjects . transformations 
contains only the class EditableLinear Transformation, 
which will eventually be able to edit lin- 
ear scene-object transformations (see package 
optics . raytrace . sceneObjects . transformations) 
and become part of TIM's interactive version. 

Appendix C. The default non-interactive TIM 

TIM's source code comes with a class called 
NonlnteractiveTIM, which can be compiled and run as 
a Java application^] that defines a studio (scene, camera and 



4 In Eclipse 1211 . simply bring up the source-code file 
optics . raytrace . Ray Trace JavaApplication. java and select Run 
> Run. 



lights); renders the scene under the conditions defined in the 
studio; and displays the rendered image on the screen and 
saves it as a . BMP file. This class can serve as an example and 
template for using TIM's source code. 

The class NonlnteractiveTIM provides three methods: 

1. getFilename returns the filename under which the ren- 
dered image is saved; 

2. createStudio defines and returns the studio, i.e. a scene, 
a camera, and lights; 

3. main calls the createStudio method, renders the image, 
displays it on the screen, and saves it as a . BMP file; auto- 
matically gets called when the NonlnteractiveTIM class 
is run as a Java application. 

Modifying these methods^] allows TIM to perform tasks that 
cannot currently be achieved in the interactive version; below 
are a few examples. 

First we discuss modifying the createStudio method, 
which changes one or more of scene, camera and lights. This 
allows the programmer to do a number of things that are not 
currently possible in the interactive version, including 

• setting parameter values by typing in formulas; 

• using Java's built-in flow control (such as for or while 
loops) and formulas to create a number of objects system- 
atically; 

• accessing classes of scene object not currently supported 
in the interactive version (e.g. MaskedObject); 

• transforming objects, e.g. rotate, move, or scale 
them (these transformations are defined in the 
optics .raytrace . sceneObjects . transformations 
package); 

• accessing additional classes of surface properties (an ex- 
ample is PictureSurf ace, which maps a picture loaded 
from a file onto a surface; other examples include several 
types of Metaref ractiveSurf ace); 

• giving surfaces combinations of surface 
properties (which can be achieved by us- 
ing the Surf acePropertyContainer or 
Surf acePropertyContainerWeighted classes); 

• changing the lights. 

Changing the behaviour of the resulting Java application al- 
together can be achieved by altering the main class. Simple 
examples include stopping the Java application from saving the 
image (by removing the relevant line in the code, or simply by 
commenting it out). By running a loop in which parameters 
change values, for example the position of a scene object or 
the camera, and by saving the rendered images with a suitable 
filename (in the simplest case ending in a number), the saved 
images can later be combined into a movie by other software. 

5 Note that overriding these methods has no effect as all are declared 
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Appendix D. Adding a new scene-object class 

Sometimes it is necessary to add a new class of scene object to 
TIM. We can distinguish the following cases, which we treat in 
more detail in the following sections: 

1. It is desirable to add a class representing a geometrical 
shape not yet represented in TIM, for example an ellipsoid 
or a torus. 

2. It is desirable to define a class representing combi- 
nations of geometrical shapes already represented in 
TIM. One reason for doing so could be to automate 
the placing and adding to the scene of the constituent 
scene objects, for example the cone and the cylinder 
that form an arrow represented by the Arrow class. 
The individual scene objects can also automatically be 
combined using the solid-geometry classes defined in the 
optics . raytrace . sceneOb j ects . solidGeometry 
package; this is how a lens is created by the 
EditableLens class. 

3. It is desirable to (re)parametrise the surface of an existing 
geometrical shape. 

4. It is desirable to add a scene-object class that is represented 
in TIM for non-interactive use to the interactive version. 

Appendix D.l. Adding a class representing a geometrical 
shape 

A geometrical shape is represented by a (non-abstract) subclass 
of the (abstract) SceneOb jectPrimitive class. This is itself 
a subclass of SceneObjectClass, an abstract class that imple- 
ments some common methods required by the SceneOb ject 
interface such as keeping a copy of the studio, the parent object, 
and the description, and providing implementations of methods 
such as getColour that reduce the task to other methods that 
remain to be implemented, such as finding the intersection be- 
tween a ray and the object. It is instructive to study the imple- 
mentation of such a class, for example Sphere. 

Any new subclass of the SceneOb jectPrimitive class 
needs to implement methods for dealing with the geometry 
of ray tracing, namely finding the intersection between a ray 
and the shape (getClosestRaylntersection); calculating 
the normalised surface normal at any possible intersection point 
(getNormalisedSurf aceNormal); and determining whether 
a position is inside the object or not (insideObject). It also 
needs to implement methods for an instance of the class to 
make an identical copy of itself (clone), or a copy that is ge- 
ometrically transformed, for example shifted, rotated, or scaled 
(transform). 

Note that the surface normal points in the direction of the 
shape's outside. In many cases, it is obvious which side of the 
surface is on the inside and which one is on the outside, for 
example in the case of a sphere. However, in other cases, for 
example in the case of a plane, it is not at all obvious. In such 
cases, the direction of the surface normal defines an inside and 
an outside. It is important to be able to distinguish inside from 
outside as many types of surface property, for example refrac- 
tion, distinguish between rays that arrive from the inside from 
those arriving from the outside. 



Appendix D.2. Defining a new scene-object class in terms of 
existing scene objects 

Sometimes it is desirable to define a new class of scene objects 
that consists of a number of scene objects of existing classes. 
Examples include the Arrow class, which represents a combina- 
tion of a cone (the arrow's tip) and a cylinder (the shaft), and the 
EditableLens class, which represents a convex-convex lens. 

The easiest way to implement such a class is to extend 
the class that represents the appropriate combination of scene 
objects. For example, an arrow, which is simply a col- 
lection of a cone and a cylinder, can be realised by ex- 
tending the class representing simple scene-object collections, 
SceneOb jectContainer; a convex-convex lens, which is the 
intersection of two spheres, can be realised by extending the 
SceneObjectlntersection class. All the class then needs 
to do (usually in the constructor) is to add the appropriate 
scene objects to the array of objects in the class, using the 
addSceneObject method. 

Appendix D.3. (Re)parametrising the surface of an existing 
shape 

A number of surface properties require a surface that has a 
two-dimensional coordinate system associated with it (section 
[4] especially Fig. [6]). An example of such a surface property 
is Surf aceTiling, which covers the surface in a chequer- 
board pattern in the surface's coordinate system. A surface 
that can calculate a pair of coordinates for any point on the 
surface is represented by the ParametrisedObject interface; 
it needs to implement methods for returning coordinates of 
an arbitrary point on the surface (getSurf aceCoordinates) 
and for returning the corresponding coordinate names, for ex- 
ample theta and phi in the case of a sphere's polar coordi- 
nate system (getSurf aceCoordinateNames). A surface that 
can also identify a point on the surface for arbitrary coordi- 
nates is represented by 0ne20neParametrised0bject inter- 
face. Such a surface needs to implement the methods required 
by the ParametrisedObject interface, and additionally the 
getPointForSurf aceCoordinates method. If the mapping 
between surface points and coordinates is not one-to-one then 
the behaviour of this method is undefined. 

Note that there are scene objects, most notably 
compound scene objects, which can implement the 
ParametrisedObject interface so that patterned sur- 
faces can be applied to each constituent scene object, provided 
it implements ParametrisedObject, but which should not 
implement the 0ne20neParametrised0bject interface even 
if all constituent scene objects do as there might be points 
on different constituent objects that correspond to the same 
combination of coordinate values, and so the mapping between 
surface points and coordinates is not one-to-one. 

A scene object that implements the ParametrisedObject 
interface also defines directions on the surface, through the 
getSurf aceCoordinateAxes call-back method. This allows 
the implementation of anisotropic surface properties, which re- 
quire a preferred direction to be defined. Fig. [6] shows these 
vectors for two points on the surface of an object of class 
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ParametrisedSphere. Their primary purpose is to define di- 
rections on the surface, which is why they many methods that 
use these vectors normalise them. An example is the surface- 
property class Metaref ractive, which allows surfaces to de- 
flect light rays in very general ways. (This can be seen as a 
generalisation of refraction at the interface between media with 
different refractive indices, or "metarefraction" (TJ.) As many 
light-ray-direction changes are internally handled through the 



Metaref ractive class (see Appendix E.2 1, it is often impor- 
tant that surfaces implement the ParametrisedObject inter- 
face. Those light-ray-direction changes include Snell's-law re- 
fraction (surface property Refractive); ray flipping, which 
changes the sign of one light-ray-direction component |20| 
(surface property RayFlipping); and ray rotation (Fig. |2j, 
which rotates the light-ray direction by an arbitrary (but fixed) 
angle around the local surface normal (surface property 
RayRotating). 

Creating a class that parametrises the geometrical shape 
described in an existing class can be achieved by creat- 
ing a subclass of the existing class. This new subclass 
needs to implement the methods of the relevant interfaces, 
ParametrisedObject or Dne20neParametrised0bject. If 
the existing class is already parametrised and the new subclass 
overrides its methods related to parametrisation, then the new 
class re-parametrises the geometrical shape described in the ex- 
isting class. 

Appendix DA. Adding an existing scene-object class to inter- 
active TIM 

All scene-object classes available in the interactive version of 
TIM need to be fully parametrised (see previous section), i.e. 
they need to implement the 0ne20neParametrised0bject 
interface. 

For a class to be editable through the mechanism built into 
the interactive version of TIM, it needs to implement the 
IPanelComponent interface. To add an existing scene-object 
class to the interactive version of TIM, it is easiest to create 
a subclass that implements the following methods required by 
IPanelComponent: 

1. createEditPanel prompts the creation of the edit panel 
(of class JPanel), an area of screen that allows interactive 
editing of any of the scene object's parameters; 

2. discardEditPanel signals to the IPanelComponent 
that the edit panel is no longer required, and any resources 
associated with it can be freed up; 

3. getEditPanel returns the edit panel; 

4. setValuesInEditPanel sets all the sub-panels in the 
edit panel to reflect the current values of the scene object's 
parameters; 

5. acceptValuesInEditPanel sets the scene object's pa- 
rameters to the edited values in the edit panel; 

6. backToFront gets invoked after editing of a different 
IPanelComponent's edit panel has been completed (for 
example, the surface property of the current scene object 
could have been edited), and this one's edit panel is being 
edited again. 



The new class can now be part of the scene, and it can be 
edited, but it is so far not possible to create a new instance 
(unless another one is being duplicated). Creating a new in- 
stance of a scene object in interactive TIM happens by adding 
a new scene object to a collection of scene objects. This col- 
lection can be "The scene", which is the top-level collection of 
scene objects, but it can also be a collection that is part of "The 
scene" (or of other collections in the hierarchy). Editing a col- 
lection is handled by the EditableSceneObjectCollection 
class. We will discuss the required steps using the example of 
the EditableTelescope class. 

1. Add a string that describes an object of this class (e.g. 
String OBJECT_TELESCOPE = "Telescope";). 

2. Add this string to the array of strings that are to be 
the menu items in the combo box responsible for ini- 
tiating the creation of a new instance of a scene ob- 
ject (e.g. String [] componentStrings = { [...], 
OB JECT.TELESCOPE , [...]};) 

3. In the actionPerf ormed method of the internal class 
SceneObjectControlPanel, which gets called when- 
ever the user interacts with the combo box that initiates 
the creation of a new scene object, add a case that gets in- 
voked when the user has selected the new object type in 
the new-object combo box. In the case of our example, it 
has the following form: 

else if (newElementName . equals ( 
OBJECT_TELESCOPE) 

) 

iPanelComponent = new EditableTelescope ( 
"Telescope", // description 
// default centre 
new Vector3D(0, 0, 10), 
// default ocular normal 
new Vector3D(0, 0, -1), 
1, // default magnification 
1, // default radius of aperture 
// parent in hierarchy 
EditableSceneOb j ectCollection . this , 
// scene, lights and camera 



getStudioO 



); 



Appendix E. Adding a surface-property class 

One of the main reasons why we wrote TIM was to be able 
to fully control the effect of surfaces on light rays, which 
has proved tremendously useful not only for our research on 
METATOYs but also for our work on optical orbital angular 
momentum. This section outlines how new surface properties 
can be added to TIM. 

Appendix E.l. Adding a general surface property 
TIM establishes the effect of a surface on any specific light ray 
by asking the getColour method of the Surf aceProperty 
object representing the surface to return the colour of the re- 
verse ray, i.e. the light ray travelling in the opposite direction. 
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The role of surfaces in establishing this colour is outlined in 



more detail in Appendix A 



A new surface property can be created by implementing 
the Surf aceProperty interface directly. The class represent- 
ing the new surface property must implement the getColour 
method. Precisely how it calculates the reverse ray's colour 
varies greatly between different surface-property classes. The 
getColour method has access to all the information being 
passed to it as arguments: 

• the Ray object describing the incident light ray contains its 
direction and starting position; 

• the RaySceneObjectlntersection object describing 
the intersection between the surface and the light ray con- 
tains the position of the intersection point and the primitive 
scene object being intersected; 

• the entire scene information is passed in the form of a 
SceneObject object; 

• information about lights is passed in the form of a 
LightSource object. 

Additionally, the trace level is passed as an argument. The class 
might also store additional information and make it available to 
be used within getColour. 

It might be instructive to study the code of a few classes that 
implement the Surf aceProperty interface directly. The fol- 
lowing two classes are perhaps particularly instructive. 

• The class Surf aceTiling is an example of a spatially 
varying surface property that calculates the local coordi- 
nates in the intersected primitive scene object's coordinate 
system. This is done by the code fragment 

( 

(ParametrisedObject) (i . o) 
) .getSurfaceCoordinates(i.p) , 

where i is the RaySceneObjectlntersection object 
describing the intersection point; i . o is the primitive 
scene object being intersected (which has to implement 
the ParametrisedObject interface here; if it does not, 
an exception is thrown); and i . p is a 3D vector describing 
the position of the intersection point. 

• The class Reflective is an example of a surface property 
that requires further ray tracing. Its getColour method 
illustrates, amongst other things, checking that the trace 
level is greater than zero and continuing backwards ray 
tracing with a new direction. The latter is achieved by the 
following code segment: 

return scene . getColourAvoidingOrigin( 
ray.getBranchRay(i.p, newRayDirection) , 
// the primitive scene object being 
// intersected 



1, // the light source (s) 
scene, // the entire scene 
traceLevel-1 
) .multiply (ref lectionCoef f icient) ; 

Note that creating the continuation of the ray using the 
original ray's getBranchRay method ensures the ray tra- 
jectory is recorded correctly (see section |5j; that the 
branch ray is being launched with a trace level reduced by 
1 ; and that the intensity of the branch ray is multiplied by 
a reflection coefficient stored in the Reflective object. 

Appendix E.2. Adding a surface property that affects only 
light-ray direction 

As surface properties that change light-ray direction in dif- 
ferent ways are of particular interest to us for the pur- 
poses of our METATOYs research, we have put in place a 
surface-property class that aims to facilitate the creation of 
new light-ray-direction-changing surface properties. The di- 
rection change itself is described by a subclass of the ab- 
stract Metaref raction class, which must provide meth- 
ods that calculate the new light-ray direction from the old 
light-ray direction for the two cases of light travelling in- 
wards, i.e. arriving from the surface's outside, or outwards, 
i.e. arriving from the inside. (Inside and outside are de- 
fined by the direction of the normalised surface normal, which 
can be obtained with the SceneObjectPrimitive class's 
getNormalisedSurf aceNormal method, and which is de- 
fined to point outwards.) These methods are the call -back meth- 
ods ref ractlnwards and ref ractOutwards. The surface- 
property class that represents this light-ray-direction change 
is of class Metaref ractive. The description of the direc- 
tion change (i.e. the implementation of the Metaref raction 
class) is passed as an argument to the constructor of the 
Metaref ractive surface property; in other words, an object 
of class Metaref ractive is always created around a specific 
light-ray-direction change. 

In TIM, most light-ray-direction changes at surfaces are de- 
scribed in terms of their projection into an Argand plane tan- 
gential to the surface at the intersection point and with its ori- 
gin placed there (section [2|i J6). A complex number that cor- 
responds to the projection of the incoming light ray is mapped 
to another complex number, which corresponds to the projec- 
tion of the outgoing light ray. The component in the direction 
of the surface normal is calculated so that the length of the di- 
rection vector remains unchanged. The mapping of the light- 
ray projection then defines the direction change; for example, 
refraction according to Snell's law is described by multiplica- 
tion with a real number, and rotation through an angle a around 
the surface normal is described by multiplication with a com- 
plex number of the form exp(ia) 0. Direction changes can be 
described in this way by the ComplexMetaref raction class, 
which is a subclass of Metaref raction. 

Examples of surface properties which have been im- 
plemented by extending the Metaref ractive surface- 
property class, and which use extensions of the 
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Figure E.15: The panel for editing the surface property an orange object. The 
top half allows selecting a surface-property class; the lower half allows editing 
of parameters specific to the selected class, in this case the red (R), green (G), 
and blue (B) values of the surface colour. The panel is created by the class 
Surf acePropertyPanel. 



ComplexMetaref raction class to describe the light- 
ray-direction change they represent, include RayFlipping, 
which represents surfaces that change the sign of one of 
the ray-direction components tangential to the surface at 
the intersection point 11201 ; RayRotating, which represents 
surfaces that rotate the light-ray direction by an arbitrary, but 
fixed, angle around the local surface normal |5|; Refractive, 
which represents standard Snell's-law refraction at the interface 
between optical media with different refractive indices; and 
Refract iveComplex, which represents a combination of 
Snell's-law refraction and rotation around the local surface 
normal, which can be described formally as refraction at 
the interface between optical media with different complex 
refractive indices 0. 

Appendix E.3. Adding an existing surface-property class to in- 
teractive TIM 

Surface properties are being selected in a panel described by the 



Surf acePropertyPanel class (Fig. E.15 i. This panel consists 
of a combo box that allows selection of the class of surface 
property, and space for editing any parameters specific to the 
selected surface-property class. 

The following modifications of the 

Surf acePropertyPanel class add an existing surface- 
property class to TIM's interactive incarnation; we 
discuss these using the example of the surface prop- 
erty describing a coloured surface (Surf aceColour in 
optics . raytrace . surfaces). 

1. Define a string constant, with a suitable name, that de- 
scribes the surface property. After completion of the steps 
below, the contents of this string will come up as an option 
in the combo box for selecting a surface-property class. In 
our example, add the lines 

private static final String 

SURFACE_PRDPERTY_DESCRIPTION_COLOURED = 
"Coloured" ; 

2. If the surface-property class requires additional parame- 
ters, define a variable that can hold the panel for edit- 
ing these parameters. In our example, this panel al- 
lows separate editing of the red, green and blue (RGB) 
components of the surface colour, and it has a label 



which helpfully points out what it is the user is edit- 
ing ("Colour"). All of this can be achieved with the 
LabelledDoubleColourPanel class, using the follow- 
ing lines of code: 

private LabelledDoubleColourPanel 
colourPanel ; 

In the constructor of the Surf acePropertyPanel class, 
create an instance of the panel for the additional parame- 
ters and initialise it with a default value: 

colourPanel = 

new LabelledDoubleColourPanel ("Colour") ; 
colourPanel . setDoubleColour ( 
DoubleColour. WHITE 

); 

3. The setSurf aceProperty method contains a chain of 
if statements that distinguishes between different surface- 
property classes of the variable surf aceProperty. Into 
this chain, link a case for the surface-property class to 
be added. In the code block for this if statement, 
add statements that make the surface-property class that 
currently selected in the surface-property-class combo 
box; set the panel for editing the surface-property-class- 
specific parameters to reflect the properties of the variable 
surf aceProperty; and ensure that the panel for edit- 
ing the class-specific parameters is shown. The following 
block of code does this for our example: 

if (surf aceProperty instanceof Surf aceColour) 
{ 

surf acePropertyComboBox . 
setSurf acePropertyString( 

SURFACE_PROPERTY_DESCRIPTION_COLDURED 

); 

colourPanel . setDoubleColour ( 
( 

(Surf aceColour) surf aceProperty 
) .getDif fuseColourO 

); 

setOptionalParameterPanelComponent ( 
colourPanel 

); 

} 

4. There is a similar chain of if statements in the 
getSurf aceProperty method. Into that chain, add 
a case that returns an instance of the new surface- 
property class with the parameters from the class-specific- 
parameters panel. In our case, the following lines do this: 

if (surf acePropertyString . equals ( 

SURFACE_PROPERTY_DESCRIPTIDN_CDLOURED 

)) 

{ 

// return a shiny version of the colour 

return new Surf aceColour ( 

colourPanel . getDoubleColour () , 

// specular component; white = shiny 
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DoubleColour . WHITE 

); 

> 

5. The remaining changes are to the internal class 
Surf acePropertyComboBox, which describes the 
combo box for selecting a surface-property class. First, 
the code for adding the string describing the new surface- 
property class to the various options available for selection 
by the combo box needs to be added to the constructor. 
This is done by adding the string constant describing the 
surface property defined above to the array of strings 
called surf acePropertyStrings. For our example, 

surf acePropertyStrings . add( 

SURFACE_PROPERTY_DESCRIPTION_COLDURED 

); 

6. Finally, in the actionPerf ormed method, a case needs to 
be added to the chain of if statements which displays the 
class-specific-parameters panel in case the user selects the 
new surface-property class in the surface-property-class- 
selection combo box. In our example, the following code 
is suitable: 

if (surf acePropertyString. equals ( 

SURFACE_PROPERTY_DESCRIPTION_CDLOURED ) 

) 

{ 

setOptionalParameterPanelComponent ( 
colourPanel 

); 

} 

For a few classes of surface property it is necessary to 
edit more parameters than fit into the space reserved for the 
surface-property panel. The way this has been achieved in 
TIM is by making the surface-property-class-specific panel 
consist of a button which, when clicked, initiates editing of 
the class-specific parameters. The details of how this has 
been implemented can be seen by studying how the classes 
describing tiled and two-sided surfaces, Surf aceTiling and 
TwoSidedSurf ace, respectively, have been incorporated into 
the Surf acePropertyPanel class. 
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